

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>fix external command &mdash; LIGGGHTS v3.X documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="LIGGGHTS v3.X documentation" href="index.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="Manual.html" class="icon icon-home"> LIGGGHTS
          

          
          </a>

          
            
            
              <div class="version">
                v3.X
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_input_script.html">3. Input Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">4. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_gran_models.html">5. Contact models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_mesh_modules.html">6. Mesh modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">7. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">8. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">10. Python interface to LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">11. Errors</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="Manual.html">LIGGGHTS</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="Manual.html">Docs</a> &raquo;</li>
        
      <li>fix external command</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/fix_external.txt" rel="nofollow"> View page source</a>
          
          <a href="http://www.cfdem.com"> Website</a>
          
            <a href="Section_commands.html#comm" rel="nofollow"> Commands</a>
            
          
        
      </li>
    
  </ul>

  
  <hr/>
  
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="fix-external-command">
<span id="index-0"></span><h1>fix external command<a class="headerlink" href="#fix-external-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>fix ID group-ID external mode args
</pre></div>
</div>
<ul class="simple">
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><em>fix</em></a> command</li>
<li>external = style name of this fix command</li>
<li>mode = <em>pf/callback</em> or <em>pf/array</em></li>
</ul>
<pre class="literal-block">
<em>pf/callback</em> args = Ncall Napply
  Ncall = make callback every Ncall steps
  Napply = apply callback forces every Napply steps
<em>pf/array</em> args = Napply
  Napply = apply array forces every Napply steps
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>fix 1 all external pf/callback 1 1
fix 1 all external pf/callback 100 1
fix 1 all external pf/array 10
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>This fix allows external programs that are running LIGGGHTS(R)-PUBLIC through its
<span class="xref std std-ref">library interface</span> to modify certain
LIGGGHTS(R)-PUBLIC properties on specific timesteps, similar to the way other
fixes do.  The external driver can be a <span class="xref std std-ref">C/C++ or Fortran program</span> or a <a class="reference internal" href="Section_python.html"><em>Python script</em></a>.</p>
<hr class="docutils" />
<p>If mode is <em>pf/callback</em> then the fix will make a callback every
<em>Ncall</em> timesteps or minimization iterations to the external program.
The external program computes forces on atoms by setting values in an
array owned by the fix.  The fix then adds these forces to each atom
in the group, once every <em>Napply</em> steps, similar to the way the <a class="reference internal" href="fix_addforce.html"><em>fix addforce</em></a> command works.  Note that if <em>Ncall</em> &gt;
<em>Napply</em>, the force values produced by one callback will persist, and
be used multiple times to update atom forces.</p>
<p>The callback function &#8220;foo&#8221; is invoked by the fix as:</p>
<div class="highlight-python"><div class="highlight"><pre>foo(void *ptr, bigint timestep, int nlocal, int *ids, double **x, double **fexternal);
</pre></div>
</div>
<p>The arguments are as follows:</p>
<ul class="simple">
<li>ptr = pointer provided by and simply passed back to external driver</li>
<li>timestep = current LIGGGHTS(R)-PUBLIC timestep</li>
<li>nlocal = # of atoms on this processor</li>
<li>ids = list of atom IDs on this processor</li>
<li>x = coordinates of atoms on this processor</li>
<li>fexternal = forces to add to atoms on this processor</li>
</ul>
<p>Note that timestep is a &#8220;bigint&#8221; which is defined in src/lmptype.h,
typically as a 64-bit integer.</p>
<p>Fexternal are the forces returned by the driver program.</p>
<p>The fix has a set_callback() method which the external driver can call
to pass a pointer to its foo() function.  See the
couple/lammps_quest/lmpqst.cpp file in the LIGGGHTS(R)-PUBLIC distribution for an
example of how this is done.  This sample application performs
classical MD using quantum forces computed by a density functional
code <a class="reference external" href="http://dft.sandia.gov/Quest">Quest</a>.</p>
<hr class="docutils" />
<p>If mode is <em>pf/array</em> then the fix simply stores force values in an
array.  The fix adds these forces to each atom in the group, once
every <em>Napply</em> steps, similar to the way the <a class="reference internal" href="fix_addforce.html"><em>fix addforce</em></a> command works.</p>
<p>The name of the public force array provided by the FixExternal
class is</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">double</span> <span class="o">**</span><span class="n">fexternal</span><span class="p">;</span>
</pre></div>
</div>
<p>It is allocated by the FixExternal class as an (N,3) array where N is
the number of atoms owned by a processor.  The 3 corresponds to the
fx, fy, fz components of force.</p>
<p>It is up to the external program to set the values in this array to
the desired quantities, as often as desired.  For example, the driver
program might perform an MD run in stages of 1000 timesteps each.  In
between calls to the LIGGGHTS(R)-PUBLIC <a class="reference internal" href="run.html"><em>run</em></a> command, it could retrieve
atom coordinates from LIGGGHTS(R)-PUBLIC, compute forces, set values in fexternal,
etc.</p>
<hr class="docutils" />
<p>To use this fix during energy minimization, the energy corresponding
to the added forces must also be set so as to be consistent with the
added forces.  Otherwise the minimization will not converge correctly.</p>
<p>This can be done from the external driver by calling this public
method of the FixExternal class:</p>
<div class="highlight-python"><div class="highlight"><pre>void set_energy(double eng);
</pre></div>
</div>
<p>where eng is the potential energy.  Eng is an extensive quantity,
meaning it should be the sum over per-atom energies of all affected
atoms.  It should also be provided in <a class="reference internal" href="units.html"><em>energy units</em></a>
consistent with the simulation.  See the details below for how to
insure this energy setting is used appropriately in a minimization.</p>
</div>
<hr class="docutils" />
<div class="section" id="restart-fix-modify-output-run-start-stop-minimize-info">
<h2>Restart, fix_modify, output, run start/stop, minimize info<a class="headerlink" href="#restart-fix-modify-output-run-start-stop-minimize-info" title="Permalink to this headline">¶</a></h2>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><em>binary restart files</em></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><em>fix_modify</em></a> <em>energy</em> option is supported by this
fix to add the potential &#8220;energy&#8221; set by the external driver to the
system&#8217;s potential energy as part of <a class="reference internal" href="thermo_style.html"><em>thermodynamic output</em></a>.  This is a fictitious quantity but is
needed so that the <code class="xref doc docutils literal"><span class="pre">minimize</span></code> command can include the
forces added by this fix in a consistent manner.  I.e. there is a
decrease in potential energy when atoms move in the direction of the
added force.</p>
<p>This fix computes a global scalar which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-8"><span>output commands</span></a>.  The scalar is the
potential energy discussed above.  The scalar stored by this fix
is &#8220;extensive&#8221;.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><em>run</em></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <code class="xref doc docutils literal"><span class="pre">minimize</span></code> command.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you want the fictitious potential energy associated
with the added forces to be included in the total potential energy of
the system (the quantity being minimized), you MUST enable the
<a class="reference internal" href="fix_modify.html"><em>fix_modify</em></a> <em>energy</em> option for this fix.</p>
</div>
</div>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div>none</div></blockquote>
<p><strong>Related commands:</strong> none</p>
<p><strong>Default:</strong> none</p>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2016, DCS Computing GmbH, JKU Linz and Sandia Corporation.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'v3.X',
            LANGUAGE:'None',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: ''
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>